Skip to main content

11.3_Complete_REST_API_Design

Here are your complete, detailed structured notes (Part 2) — continuing from the previous notes, covering filtering, CRUD APIs, status codes, custom actions, consistency, and best practices.

REST API Design – Advanced Notes (Filtering, CRUD, Custom Actions)

Filtering in List APIs​

Concept​

  • Filtering allows clients to narrow down results based on conditions
  • Works via query parameters

Example: Filter by Status​

  • Query:

    • ?status=archived

  • Result:

    • Only organizations with status = archived returned

Multiple Filters​

  • Example:

    • ?status=active&name=org1

  • Server applies:

    • AND condition (typically)

Key Idea​

  • Filtering = server-side selection of subset of data

  • Works alongside:

    • Pagination
    • Sorting

CRUD APIs – Complete Flow

Update API (PATCH)​

Why PATCH (Preferred)​

  • Usually update partial fields
  • Common in modern apps (JSON-based SPAs)

Endpoint Pattern​

PATCH /organizations/{id}
  • Uses dynamic parameter (ID)

Request Body Example​

{
  "status": "active"
}

Response​

  • Status: 200 OK

  • Returns:

    • Updated entity

Get Single Resource​

Endpoint​

GET /organizations/{id}

Behavior​

  • Returns:

    • Single resource

  • Status: 200 OK

Delete API​

Endpoint​

DELETE /organizations/{id}

Response​

  • Status: 204 No Content
  • Body: empty

Why No Content?​

  • Resource is deleted
  • Nothing left to return

Error Handling​

404 Not Found​

  • When:

    • Requesting specific resource
    • Resource does not exist

Example:

GET /organizations/6 → 404

Important Rule​

  • List API (GET /resources):

    • Return 200 with empty array

  • Single resource API:

    • Return 404 if not found

Example​

GET /organizations?status=random
→ data: []
→ status: 200

Custom Actions (Very Important)

What are Custom Actions?​

  • Actions that:

    • Don’t fit CRUD
    • Trigger complex backend logic

Example: Archive Organization​

  • Not just:

    • status = archived

  • Might also:

    • Delete projects
    • Notify users
    • Clean related data

Endpoint Design​

POST /organizations/{id}/archive

Structure​

  • Resource hierarchy:

    • /organizations/{id} → specific resource
    • /archive → action

Response​

  • Usually:

    • 200 OK

  • Not always 201 (depends on action)

Project APIs (Pattern Reuse)

Key Insight​

  • Same patterns apply to all resources:

    • organizations
    • projects
    • tasks

Create Project​

POST /projects

Payload​

{
  "name": "Project 1",
  "organizationId": "...",
  "status": "planned",
  "description": "..."
}

JSON Best Practice​

  • Always use camelCase
  • Maintain consistency across APIs

List Projects​

GET /projects

Supports:

  • Pagination
  • Sorting
  • Filtering

Get Single Project​

GET /projects/{id}

Update Project​

PATCH /projects/{id}

Delete Project​

DELETE /projects/{id}

→ Returns 204 No Content

Custom Action: Clone Project​

Why Not POST /projects?​

  • Clone may:

    • Copy tasks
    • Send emails
    • Trigger workflows

Endpoint​

POST /projects/{id}/clone

Behavior​

  • Creates new project

  • Returns:

    • 201 Created (since new resource created)

API Design Best Practices

1. Consistency (MOST IMPORTANT)​

  • Across:

    • Routes
    • Payloads
    • Responses

Example​

  • If using:

    • description → always use same key

  • Avoid:

    • desc, dsc etc.

2. Naming Rules​

  • Use plural resources:

    • /organizations
    • /projects

  • Avoid mixing styles

3. Avoid Abbreviations​

  • Bad:

    • desc

  • Good:

    • description

Reason:

  • Avoid confusion for API consumers

4. Provide Sensible Defaults​

For GET APIs​

  • Default:

    • page = 1
    • limit = 10/20
    • sort = createdAt desc

For POST APIs​

  • Example:

    • Default status = active

5. API Should Be Intuitive​

  • No guesswork required
  • Easy to use without reading code

6. Documentation​

  • Use:

    • Swagger / OpenAPI

Benefits​

  • Interactive testing
  • Clear contract
  • Better integration

Design Philosophy

APIs Are Designed First​

  • NOT coded first

Process​

  1. Design interface
  2. Define behavior
  3. Then implement logic

Why?​

  • Helps:

    • Think like API consumer
    • Avoid bad design
    • Ensure consistency

Tools​

  • Postman / Insomnia → design
  • Swagger → documentation

Final Takeaways

  • CRUD + Custom actions form full API system

  • POST = flexible method for non-standard operations

  • Always:

    • Keep APIs consistent
    • Follow REST semantics
    • Provide defaults
    • Avoid ambiguity

  • Think from:

    • Client perspective, not backend